Our Journey to a streamlined GitHub Organization: Community Health and other organizational topics

Simon Schrottner

December 6, 2022

Maintaining an open source project is more than maintaining good code.

As noted in my previous blog post, I currently find myself on a journey to transform our unorchestrated Dynatrace GitHub organizations into a more structured and managed approach with a streamlined process that allows us to handle users, repositories, and organizations in a more accessible way.

In my first post, I gave an overview of the issues and how we plan to tackle them. In this post, I’ll go into more detail about one of these issues: Community health.

Open Source is getting more and more present in the daily lives of us developers. However, doing open source properly can take time and effort. There are a lot of ceremonial standards to adhere to, and often it’s not easy for developers to find that sweet spot in compliance.

Questions like “What general files do I need?” or “What should be mentioned in them?” arise continuously and must be answered. Standards increase the overhead for developers to make their code open source. And additionally, maintaining those files can also be quite tricky. And even though websites are dedicated to supporting developers with open source, like the Open Source Guides, errors still occur.

At the Open Source Program Office, we aim to make this process easier for developers and reduce their boilerplate. We aim to provide a default but allow overwrites and project autonomy.

Let’s dig into our approach.

What is Community Health?

As already mentioned, there are a lot of ceremonial standards, and keeping the community healthy is also part of good maintainership. A good community excels with easy onboarding of contributors and reporters and clear and respectful communication. Simply put, it allows everyone within the community to grow and succeed in their adventures.

The OSPO team can’t take over the responsibilities of good maintainership for all projects at Dynatrace. We can only educate our maintainers and help them to grow and maintain a healthy community. But there are specific standards we can help our maintainers to adhere to, like all the files which share essential information about the project and how to interact with it:

Code of Conduct
Contribution Guidelines
Security Policy
ReadMe
License

GitHub has an API endpoint for community metrics for checking already mentioned files, but it also includes issue and pull request templates. Those templates help new contributors and/or reporters share all the necessary information.

Defining a GitHub-organization-wide standard for community files

Keeping those files up-to-date or ensuring their presence all the time is close to impossible. Luckily the presence of a “Code of Conduct,” “Contribution Guidelines,” “Security Policy,” and even the templates can be managed for the whole GitHub Organization in a centralized manner. GitHub allows the creation of a repository called .github, which can contain all those files and will be used as a fallback if they’re not present within a repository.

For us, this is the ideal solution. Most of our projects don’t diverge from the standard anyways. Those who do most likely have a reason, and therefore they’re aware of those files anyways.

Other benefits of the .github-project

The most extraordinary thing about the .github-repository is that it can additionally store organization-wide configurations for ProBot applications like in-solidarity-Bot and, for example, renovate. It allows us to quickly roll out tools with a default configuration for all our repositories. This ceremonial automation often doesn’t need to be part of the git history, nor does it have to be part of the source code of a repository. Removing it reduced the bloat within the repositories and allowed us to focus more on the repository mission.

Another nice feature of the .github-repository is the possibility to create a GitHub Organization ReadMe.

This ReadMe will be rendered on the organization page, and we will use this to share general information about open source efforts at Dynatrace.

How do we handle files not covered by .github?

The .github-repository already covers a big part, but sadly only some things. There is still an issue with ReadMe and the License since those must be project specific.

License

As we can’t provide a default License file, we’re “forced” to use monitoring and alerting. License information is crucial, especially as not everything we put on GitHub is meant to be used by anybody. Some of our repositories are on GitHub because we develop them in an open/accessible manner, but they’re proprietary. Therefore, this license information is essential for others to verify what they’re legally allowed to do with our code.

ReadMe

As the ReadMe document describes the project, providing a global one doesn’t make sense. In the next section, we will go into more detail about how we provision repositories and what we’re providing “out of the box.”

Streamlining repository creation

As we realized that handling the ReadMe and the License files can’t be done with a centralized repository, we needed to think about the best way to achieve our goal.

In the end, the only reasonable and suitable way to ensure our defaults is to handle them during repository creation. The license file is easy, as it does not need any attention from a maintainer. On the other hand, ReadMe is highly project-specific and needs attention.

GitHub allows you to define a repository template with all kinds of files you want to have in place when having a project setup. So the ideal place to place our default license. As this is also the entry point for our future maintainers, we tried to create a gamified ReadMe list of todos and things to take care of. Our template project shows how we greet new maintainers and elaborate on all the things that need attention and how to achieve that this project will be public.

Our template project is also enhanced with some good-to-have tools, like Markdownlint and a GitHub Action for continuous checks on pull requests. This ensures that our markdown files are formatted consistently and properly.

Help our existing users

In the last two chapters, we covered our template project and our .github project. Also, we shortly mentioned that we could create a GitHub Organization Landing Page with a ReadMe to share information with others.

As our processes are sometimes more complex than we want them to be, we also want to have a prominent place on GitHub to guide our employees and organization members. For things such as: How they can invite co-workers or how they can reach an admin. The usual help questions. Luckily GitHub also has us covered regarding this topic.

The second reserved repository name is .github-private, which allows us to replace the landing page for members with a different ReadMe.

Additionally, this repository does not have to be public; it can or should be private. This allows us to share more sensitive data, like links to Jira or internal documentation.

Looks cool, but how to apply this to multiple GitHub Organizations?

This works great as long as you’re only working in one GitHub Organization, maybe it is feasible for up to 5 organizations, but keeping this up-to-date throughout our organization jungle is impossible. For n organizations, we have n*3 additional repository to update manually. Furthermore, we would need to agree to a process for all of them, handle deviations, etc.

Taking all of this into account, we decided that, at least for the .github and the .github-private-repository, we try to keep them as general as possible. Therefore, we can follow a similar approach to the .github repository on an organization level.

As this is a homegrown solution, there is sadly no automation. But we do have default repositories within one organization, and the others rely on those, aka forks from our OSPO GitHub organization to all the others.

GitHub allows you to update these forks via UI (so far, I am still looking for the API for that). This way, you have at least a default. Users can deviate from it — as long as they know what they’re doing — and updates can be shared easily.

Summary

Our big goal is to have a good experience for our maintainers and developers by reducing some boilerplate and making onboarding new repositories as smooth as possible. The .github-repository, the .github-private-repository, and the template project help us to achieve this. With simple forks to all our GitHub Organization, we found a suitable solution to reduce the manual effort. Most importantly, we can easily spot the differences without overwriting local changes.

So far, we think we’re on the right path — at least we have not heard anything else — but there might be better-suited solutions to our problem. If you do think you know some or are aware of a different approach, please let us know.

Written by